This PR gives the options of the .. code-block:: directive to the .. doctest::, .. testcode:: and .. test_output:: directives from the doctest extension.

These options are:

• linenos
• lineno-start
• emphasize-lines
• force
• caption
• name
• class
• dedent

Purpose

The goal behind this is for users to be able to switch from code-block to testcode or doctest directives extremely easily, so that they can test their documentation's code without losing the super nice display options that code-block offers. Note that this was a problem that I recently had myself, and that prevented me from using doctest.

I also think that it makes sense for the testcode, testoutput and doctest directives to be strongly coupled with the code-block directive (I think we want them to be code blocks with some extra testing), which is why I decided to use inheritance.

Implementation details

To avoid code duplication and ensure that the options supported by the doctest-related directives will not diverge from those of code-block over time, this makes the TestDirective class extend a new BaseCodeBlock class, that contains what was in CodeBlock, but without the language argument (language can only be python for doctests, so it doesn't make sense to have a language argument for doctest-related directives).

CodeBlock usage should not change at all: it now extends BaseCodeBlock + adds the language optional argument that it already had before, that was stripped from BaseCodeBlock.

There is some special care for when there is a caption: this is because when a caption is provided, the literal_block created by BaseCodeBlock is wrapped in a container. Changes to this literal_block should thus be made to the wrapped literal_block and not to the container itself.

Examples

example.rst:

Some examples
=============

These examples shows how the directives from ``sphinx.ext.doctest`` can now be used with the options
from the ``.. code-block::`` directive.

The first example (:ref:`example`) is made using the ``.. testcode::`` directive, and the second
example (:ref:`example-2`) uses the ``.. doctest::`` directive.

.. testcode:: group
    :emphasize-lines: 3
    :linenos:
    :name: example
    :caption: Code block 1

    a = 5
    b = 6
    assert True


.. doctest:: group-2
    :emphasize-lines: 3
    :linenos:
    :name: example-2
    :caption: Code block 2

    >>> a = 5
    >>> b = 6
    >>> print(a + b)
    11

built html page (using furo theme):

Disclaimers

• This is my first time contributing to sphinx. I have very limited knowledge of the codebase, so I may have made some bad choices.
• I used claude code to fix a few bugs that I originally introduced (improper care of the caption, improper handling of the <BLANKLINE>. I also used it to generated all of the unit tests. The rest was manually coded, and the architectural decisions were mine.
• I think some of the unit tests that claude introduced may be deleted, and maybe we could add some new ones. I would appreciate guidance from a maintainer to know what to do there.
• I didn't find how to update CHANGES.rst. It seems to be only for changes that were already released.
• I only added a single sentence to doc/usage/extensions/doctest.rst, saying that all of the options from code-block are also available in the doctest directives that build visible code blocks. We could instead list all of those options like the other options of those directives. This would be a bit more work to maintain, because it would lead to some duplication. But it would also make it easier for users to see that these options exist.
• Feel free to edit my branch!

References

• Fixes Add :caption: for .. doctest:: #6915
• Fixes testcode directives should support the same options as code-block #6858